Summary

This PR consolidates three coherent change sets:

1. Docs/governance and contributor workflow hardening
2. Renderer e2e stabilization for reliable smoke checks
3. Desktop runtime/auth/API hardening, including BYO secure endpoint diagnostics and environment-driven labs policy

Scope

1) Docs + Governance + Workflow

• Refreshed and normalized docs across docs/ (ownership/review metadata consistency, backlog and decision-log updates, index alignment)
• Updated docs/docs-index.md to reflect current documentation set
• Merged unique content from the transient security checklist into canonical workflow docs and removed the duplicate transient file
• Added docs-lint script and enforced it via pre-commit
• Added CURRENT-SPRINT.md to track active sprint scope
• Removed tracked TASK.md (intentionally transient/local)

2) E2E Stability

• Stabilized Playwright smoke execution
• Confirmed clean-port test-server behavior for deterministic e2e checks
• Retained non-fragile checks:
  • shell render sanity
  • no console/page errors on launch
  • basic accessibility gate

3) Desktop/Auth/API Hardening

Auth lifecycle and token persistence

• Added explicit OIDC lifecycle tests (OidcService)
• Hardened refresh-token lifecycle:
  • sign-out revocation + local token clear behavior covered
  • session rehydration from persisted refresh token
  • async token-store writes are now awaited (no fire-and-forget race)
• Improved token-store fallback observability (keytar vs encrypted/plain fallback)
• Added native:rebuild:keytar helper script

API BYO endpoint refactor + diagnostics

• Replaced specific operation naming with generic secure operation:
  • portfolio.user -> call.secure-endpoint
• Introduced endpoint config model:
  • API_SECURE_ENDPOINT_URL_TEMPLATE
  • API_SECURE_ENDPOINT_CLAIM_MAP (placeholder -> JWT claim path)
• Added safe custom header pass-through (x-* only)
• Added operation diagnostics channel/method to inspect runtime API operation config
• Added resolved request path in API invoke success payload for runtime traceability
• Updated API Playground to display:
  • operation diagnostics
  • token diagnostics
  • resolved request path
  • clarified placeholder precedence (params override claim-map fallback)
• Updated runtime/app contract to expose appEnvironment

Environment-driven Labs toggle policy

• Labs mode is now runtime-policy driven:
  • development / staging: forced ON
  • production: forced OFF

Validation

Executed and passing:

• pnpm nx run contracts:test
• pnpm nx run desktop-main:test
• pnpm nx run renderer:build
• pnpm nx run desktop-main:build
• pnpm docs-lint
• pnpm nx run renderer-e2e:e2e (previous run in this series)

Security (Required For Sensitive Changes)

• Security review completed
• Threat model updated or N/A explained

Security Notes

• Threat model link/update: docs/03-engineering/security-review-workflow.md
• N/A rationale (when no threat model update is needed): Existing threat model process remains valid; no new trust boundary was introduced beyond already documented renderer/preload/main boundaries.

Notes / behavior clarifications

• Auth launch diagnostics now confirm direct IdP authorization endpoint usage.
• API placeholder resolution order:
  1. request params
  2. mapped JWT claim path fallback
• Resolved Path is now surfaced in API Playground response details.